<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<title>org.argouml.gef package</title>
<!--
   Copyright (c) 1996-99 The Regents of the University of California. All
   Rights Reserved. Permission to use, copy, modify, and distribute this
   software and its documentation without fee, and without a written
   agreement is hereby granted, provided that the above copyright notice
   and this paragraph appear in all copies.  This software program and
   documentation are copyrighted by The Regents of the University of
   California. The software program and documentation are supplied "AS
   IS", without any accompanying services from The Regents. The Regents
   does not warrant that the operation of the program will be
   uninterrupted or error-free. The end-user understands that the program
   was developed for research purposes and is advised not to rely
   exclusively on the program for any reason.  IN NO EVENT SHALL THE
   UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT,
   SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING LOST PROFITS,
   ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF
   THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF
   SUCH DAMAGE. THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY
   WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
   MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE
   PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND THE UNIVERSITY OF
   CALIFORNIA HAS NO OBLIGATIONS TO PROVIDE MAINTENANCE, SUPPORT,
   UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
-->
</head>
<body bgcolor="white">


<p>This package contains classes that supply content handlers to a
SAX parser that will read
GEF diagrams in XML format (PGML files) and create
the correspondig GEF diagram objects.</p>
<p>The classes in this model implement two distinct approaches to organizing
the content handlers: a state machine and a stack-based approach.</p>
<h2>State Machine Parser</h2>
<p>
The PGMLParser class parses PGML files with
a single ContentHandler that is based on
a state machine; the current state determines how each SAX event will be handled.</p>
<h2>Stack-Based Content Handler</h2>
<p>
The remaining classes and interfaces
in the package implement a parser for PGML files that is
based on a stack of ContentHandler objects.  Everytime the SAX parser
encounters the start of an element, a new ContentHandler object is pushed
on the stack and the SAX parser sends further events to that ContentHandler.
When the parser detects the end of an element, the current ContentHandler is
popped off the stack and the SAX parser sends further events to the
underlying handler.  The number of ContentHandler objects on the stack always reflects
the nesting depth of elements at the SAX parser's current position in the document.
This represents a more rigidly structured way of representing the parser
state than the state machine used by PGMLParser, and is supposed to provide
a more robust foundation on which to implement specialized diagram-reading behaviour in
clients of the package.
</p>
<p>
{@link PGMLStackParser PGMLStackParser} is designed to be a drop-in replacement
for {@link PGMLParser PGMLParser} for clients that wish to move to the new
parsing model.  Its implementation of the {@link HandlerFactory HandlerFactory}
interface contains the logic for producing the appropriate content handler
for each element that might appear in the PGML file.  Clients can customize
parsing behavior by sub-classing PGMLStackParser; in addition, any client-provided
implementation of ContentHandler can assume full control over how sub-elements
of that element are parsed.
</p>
</body>
</html>


